fix(calls/ios): 14 defect classes that do not compile — or silently never fire — against CometChatCallsSDK 5.0.4 - #489

…ted onSearchBarClicked and onSearchTextChanged events in CometChatConversations; enhanced core features with Quoted Reply and Advanced Search sections; updated Message List and Message Header with new options; added customization examples for message item views.

…DK 5.0.4

Found while building the headless iOS calling skill (ENG-38735) by extracting
every Swift fence under /calls/ios/** and type-checking it against the SHIPPED
CometChatCallsSDK 5.0.4 + CometChatSDK 4.1.7 frameworks. Each defect is
confirmed three ways: the live PR #482 preview, the shipped .swiftinterface, and
the calls-core/ios-sdk source.

D1  AudioModeType does not exist — 17 occurrences across 6 pages, including a
    whole "AudioModeType Values" accordion. The real enum is AudioMode
    (calls-core CallModels.swift:305); 0 hits in the interface AND 0 in the
    binary's exported symbols. The fix is NOT a rename: the docs' example
    implements MediaEventsListener, whose real signature is
    onAudioModeChanged(audioMode: AudioMode) — so the parameter LABEL was wrong
    too, along with the ObjC selector and the AudioModeType*Speaker constants.

D2  CometChat.CallStatus -> CometChat.callStatus (lowercase c). ringing x2.
    rejectCall(sessionID:status:) takes CometChat.callStatus (CometChatSDK
    4.1.7 L549/L1816). Swift is case-sensitive; the documented line cannot
    compile.

D3  .setType(.video) -> .setSessionType(.video) — 8 occurrences across 5 pages.
    SessionSettingsBuilder has no setType (calls-core
    SessionSettingsBuilder.swift:120). Includes migration-guide-v5, where it sat
    under the *v5* tab, i.e. presented as the new API.

D4  The SPM URL 404s. github.com/cometchat/cometchat-calls-sdk-ios returns 404;
    the package is at github.com/cometchat/calls-sdk-ios (its Package.swift
    declares name "CometChatCallsSDK"). This is step 2 of installation, so it
    breaks before a reader writes a line of code.

D5  region documented as "us or eu" — `in` is also valid and is what several
    live apps use. The SDK does not restrict it (calls-core CometChatCalls.swift
    only guards region.length > 0), and the CHAT SDK docs already say
    "us", "eu", "in". 3 occurrences.

D6  .setAppId()/.setRegion() are @available(deprecated) in 5.0.4 — "Use
    set(appID:) instead" (calls-core CallAppSettingsBuilder.swift:70-78). Both
    spellings are public, so this compiles with a warning rather than failing;
    the docs should teach the supported pair.

D7  call.callInitiator?.name does not compile. callInitiator is AppEntity?
    (CometChatSDK 4.1.7 L950) and `name` lives on User : AppEntity (L1864/1869),
    so it needs a downcast. The ObjC variant has the same bug.

D8  The migration guide's init snippet says "No changes required" and then shows
    CallAppSettings() followed by .set(appId:)/.set(region:). CallAppSettings has
    ONLY init() — no setters at all (calls-core CallAppSettings.swift:12); the
    setters are on CallAppSettingsBuilder, and it is set(appID:) with a capital
    ID. Corrected to the builder + .build(), and verified to compile.

Verification: all 8 classes now return 0 across all 25 /calls/ios pages, and the
corrected fences type-check. Of the 50 fences on the edited pages, the only
remaining failures are snippet fragments referencing reader-supplied variables
(authToken, sessionID, callViewContainer, listener instances) — expected in
documentation, not defects.

NOT changed, deliberately: bare `AudioMode` was initially flagged as ambiguous,
but that was an artifact of the test harness importing BOTH SDKs. These pages
import only the Calls SDK, so bare AudioMode is correct here. The ambiguity is
real for an app doing 1:1 ringing (which needs both SDKs) and is recorded in the
skill instead of over-qualifying every page.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

A second pass against the shipped CometChatCallsSDK 5.0.4 and CometChatSDK
4.1.7 interfaces, plus the Chat SDK's generated CometChatSDK-Swift.h, turned
up three classes the first pass missed. The first pass grepped for the Swift
form `.setType(` with a leading dot, which never matched the Objective-C
`setType:` spelling, so every ObjC tab went unchecked.

D9 — phantom `CallType` on SessionSettingsBuilder (12 sites, 5 files)
  `CallType` does not exist in CometChatCallsSDK at all (0 occurrences in the
  .swiftinterface). It exists only in the Chat SDK, as the nested
  `CometChat.CallType` on the `Call` object. The builder's real API is
  `setSessionType(_ sessionType: SessionType)`. Fixed the method name, the
  parameter table, the accordion title and the enum-values table.
  `.audio` is additionally deprecated on SessionType ("Use voice instead"),
  so audio-only is now documented as `.voice`.

D10 — Objective-C snippets that cannot compile (2 files)
  setup.mdx used the deprecated `setAppId:`/`setRegion:` selectors; the
  current ones are `setWithAppID:`/`setWithRegion:` (verified in the framework
  binary). Both that snippet and the session-settings builder chain also had
  unbalanced brackets — 3 opens for 5 messages and 7 for 8 — so neither would
  build. All ObjC fences across the 25 calls/ios pages now balance.

D11 — invented `CometChat`-prefixed ObjC enum constants (2 files)
  `CometChatCallType`, `CometChatCallTypeVideo`, `CometChatReceiverType`,
  `CometChatReceiverTypeUser`, `CometChatCallStatusRejected` and
  `CometChatCallStatusCancelled` are not emitted by the Chat SDK. The header
  declares `CallType`/`CallTypeVideo`, `ReceiverType`/`ReceiverTypeUser` and
  `callStatus`/`callStatusRejected`/`callStatusCancelled` (lowercase prefix,
  because the Swift enum is `CometChat.callStatus`).

ringing.mdx lines 45/61/99 keep `CometChat.CallType` with `.video`/`.audio`
deliberately — that is the Chat SDK type on the ringing path and is correct.
call-logs.mdx keeps `setWithCallType:SessionTypeVideo`, which matches
`CallLogsBuilder.set(callType: SessionType)`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

`Participant` has exactly 12 properties, all Optional: uid, name, avatar, mid,
state, isJoined, joinedAt, leftAt, deviceID, totalAudioMinutes,
totalVideoMinutes, totalDurationInMinutes.

The docs used SIX properties that are not on the type at all — pid, role,
audioMuted/isAudioMuted, videoPaused/isVideoPaused, isPinned, isPresenting and
raisedHandTimestamp — across code samples and two "Participant Object
Reference" tables in which 7 of 10 rows were fabricated.

This is not a theoretical defect. Two independent review agents building from
these pages produced code that swiftc rejected:

  value of type 'Participant' has no member 'pid'
  value of type 'Participant' has no member 'isPresenting'

WHAT CHANGED

- actions.mdx, participant-management.mdx: `participant.pid` -> `participant.uid`
  in the mute and pause-video samples (Swift + Objective-C). `uid` is `String?`
  while `muteParticipant(participantId:)` takes a non-Optional `String`, so the
  samples now unwrap it. Both property tables replaced with the 12 real fields,
  correctly typed as Optionals.

- raise-hand.mdx "Check Raised Hand Status" and screen-sharing.mdx "Check Screen
  Share Status" were built entirely on `raisedHandTimestamp` / `isPresenting`.
  Rewritten to accumulate the state from onParticipantHandRaised/Lowered and
  onParticipantStartedScreenShare/Stopped, keyed by uid, with cleanup on
  onParticipantLeft (a participant who leaves mid-share never sends a stop).

- custom-participant-list.mdx was the worst affected: its cell rendered five
  phantom flags, and Step 4 discarded every state event with the comment "Table
  will update via onParticipantListChanged" — which cannot work, since that
  payload carries no flags. Introduced a `ParticipantStatus` model (Swift struct
  / ObjC class) held by the view controller and driven by the events, and
  threaded it through configure(), the data source and the pin toggle. Also
  fixed, in passing: `muteParticipant(participant.uid)` was missing its argument
  label, and the search filter called `localizedCaseInsensitiveContains` on an
  Optional `name`.

A <Warning> on each rewritten page states the consequence honestly: these events
fire only on change, so a client joining mid-call cannot recover state that was
already in effect. There is no getter and no snapshot — that is a real SDK
limitation, not a doc omission.

NOT CHANGED (checked, correct as-is)
- custom-control-panel.mdx's `isAudioMuted`/`isVideoPaused` are the sample's own
  local variables — already the right pattern.
- migration-guide-v5.mdx's `CometChatCalls.audioMuted(true)` are genuine v4
  statics shown as the OLD API; their v5 targets muteAudio()/pauseVideo() all
  exist.

VERIFICATION
- Every participant-typed member access across all 25 calls/ios pages now
  resolves to `uid` or `name`; nothing else.
- All 13 Objective-C selectors used here confirmed present in the shipped
  CometChatCallsSDK 5.0.4 framework binary.
- Every ObjC fence in calls/ios still has balanced brackets (0 unbalanced).
- The uid + local-state pattern is compile-proven: both review emits that had
  failed on the phantom fields now pass swiftc and the simulator round-trip.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…ed + phantom Calls APIs

CometChatPushNotifications 1.0.0 is published (CocoaPods trunk 2026-07-24, and
an SPM binaryTarget on the cometchat/push-notifications-sdk-ios v1 branch) and
is the recommended way to add push + VoIP to an iOS app. It had NO documentation
anywhere in this repo — a search for the SDK by any name returned zero pages —
while its own podspec `documentation_url` points at /notifications/push-overview,
which routes to a guide that predates it.

NEW: notifications/ios-push-notifications-sdk.mdx

The three-step integration, verified line by line against the SDK source:
initialize(config:) + delegate, forward the APNs token, implement
CometChatPushNotificationsDelegate. The app writes no PKPushRegistryDelegate and
no CXProviderDelegate — the SDK owns both.

Every symbol on the page was checked against the source before writing it, and
the distribution facts were checked against the live public repo rather than the
private one:

- SPM URL github.com/cometchat/push-notifications-sdk-ios (200). NOTE: the
  private repo's podspec `s.source` points at cometchat/push-notifications-ios,
  which 404s, and its README's SPM URL is still the literal placeholder
  `https://<your-git-host>/CometChatPushNotifications`. Neither is usable; the
  page documents the URL that actually resolves. Raised separately against the
  SDK repo.
- The import is `CometChatPushNotificationsSwift` (the podspec's module_name),
  not `CometChatPushNotifications` (the class). Called out explicitly — it is
  the first thing that will not compile otherwise.
- No subspecs are documented. The private podspec has Core/Calls/FCM and its
  README advertises `pod 'CometChatPushNotifications/Core'`, but the PUBLIC
  podspec consumers actually get is a single vendored xcframework with none of
  them, so that install line fails.
- iOS 15.1 floor, CometChatSDK >= 4.1.5, CometChatCallsSDK >= 5.0.0, from the
  public podspec.

FIXED in notifications/ios-apns-push-notifications.mdx

- `CometChatCalls.audioMuted(_:)` and `CometChatCalls.endSession()` are
  @available(deprecated) in Calls SDK 5.0.4. Replaced with the successors the
  SDK's own deprecation messages name: CallSession.shared.muteAudio()/
  unmuteAudio() and CallSession.shared.leaveSession().
- Three editorial leaks removed. Two comments read "Removed
  CometChatCalls.startAudioSession() as per instructions" — internal review
  notes shipped to public docs, naming two methods that exist in NEITHER SDK
  (0 occurrences in the Calls and Chat interfaces). A third read
  "MARK: - CRITICAL: Audio Session Delegates (MISSING IN YOUR CODE)".

DELIBERATELY NOT CHANGED

`CometChatCallsSDK.CallSettingsBuilder` on that page is deprecated in the Calls
SDK, but CometChatOngoingCall.set(callSettingsBuilder:) takes `Any?` and
force-casts to `CallSettingsBuilder` internally, so the UI Kit still requires it.
Swapping in SessionSettingsBuilder would crash. That is UI Kit product debt, not
a docs defect.

Cross-linked from push-overview (as the recommended iOS card), from
calls/ios/voip-calling, and from the manual APNs guide, so the hand-wired path is
reachable but no longer the default. docs.json nav updated; JSON revalidated.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…ot init

Caught by driving the new page through the skill pipeline: a review agent
building from it flagged the cold-start sequence as a race, and the SDK source
confirms it.

`notifyCallsSDKReady()` only sets `isCallsSDKReady` and fires the buffered
`presentCallScreen`. It does NOT check `CometChat.getLoggedInUser()` or any
Calls-SDK auth state. So calling it at `CometChatCalls.init` success — which is
what the SDK's own README and docstring say, and what this page said — releases
the buffered call while the session is still unauthenticated, and the
`joinSession` that follows `presentCallScreen` fails on auth.

The example now releases from the `login` success instead.

Also documents a constraint that was nowhere: `presentCallWhenReady` schedules a
3-second safety timeout that fires the buffered presentation even if
`notifyCallsSDKReady()` was never called, so the call is never silently dropped.
A cold start whose login takes longer than 3s therefore reaches
`presentCallScreen` before login completes, and the call screen must not assume
a live session.

The same correction was applied to the cometchat-ios-v5-sdk skill.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…actually ships

A review agent building from this page reported that it "ships a call that
vanishes when the user leaves the screen and reports success." Verified against
the source, and the page was incomplete rather than wrong:

- CallSession.enablePictureInPictureLayout() only calls
  emitEvent(CallSessionEventIDs.enablePictureInPictureLayout) — it re-lays-out
  the call UI and creates no window. On its own nothing visible happens. The
  page's Note said as much but then offered no mechanism, so the reader is left
  with a method that appears to do the job and doesn't.
- PiPViewCoordinator IS the mechanism, it is fully public
  (calls-core sdk/src/Features/Picture-In-Picture/PiPViewCoordinator.swift,
  exported in the shipped 5.0.4 .swiftinterface, and in the skill catalog) and it
  appeared on ZERO pages across this entire docs repo.

The page conflated two different features under one name. It now separates them:

  In-app PiP  — a draggable tile over YOUR app. PiPViewCoordinator, ships in the
                Calls SDK, needs no capabilities.
  System PiP  — floats over OTHER apps. Apple's AVPictureInPictureController;
                the SDK does not implement it. Only this path needs Background
                Modes and an AVPictureInPictureVideoCallViewController.

Both still call enable/disablePictureInPictureLayout() so the SDK reshapes the UI.

Added a worked in-app example and a member reference: init(withView:) on the same
view passed to joinSession(container:), configureAsStickyView(withParentView:)
(the page now says to pass the parent explicitly, because with no argument the
implementation falls back to UIApplication.keyWindow), show/hide,
enterPictureInPicture, resetBounds on rotation, stopDragGesture,
configureExitPiPButton, the four initialPositionInSuperView corners, and
dragBoundInsets.

One semantic worth stating that the source makes clear and no doc did:
PiPViewCoordinatorDelegate.exitPictureInPicture() fires AFTER the coordinator has
already restored the full-size view — it is a notification that PiP ended, not a
request to end it. The example therefore only calls
disablePictureInPictureLayout() there.

The tile size claim is verbatim from the SDK: `c` is
@available(deprecated, message: "The PiP window size is now fixed to 150px.")

VERIFICATION
- All 17 symbols used here confirmed present in the shipped 5.0.4 .swiftinterface.
- The Swift example COMPILES: staged into the ios-calls harness against
  CometChatCallsSDK 5.0.4 + CometChatSDK 4.1.7 — BUILD SUCCEEDED.

NOT CHANGED: the AVAudioSession disagreement between this page and
/calls/ios/background-handling. background-handling claims the SDK "automatically
handles audio session configuration", and that is not provably wrong — the
shipped binary references RTCAudioSession (22x), AVAudioSession (6x) and
setCategory (4x) through the bundled WebRTC. I could not determine from the
artifact whether System PiP additionally requires the app to set the category
itself, so I left both sections alone rather than assert either way. Worth a
ruling from the Calls team.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…, one L

The docs wrote `onIncomingCallCancelled(cancelledCall:error:)`. The Chat SDK
4.1.7 interface declares `onIncomingCallCancelled(canceledCall:error:)` — the
METHOD name has two Ls, the ARGUMENT label has one. The Objective-C tab had the
same defect in the exported selector: `...WithCancelledCall:` vs the generated
header's `onIncomingCallCancelledWithCanceledCall:`.

This is the nastiest class of defect on the tree: it COMPILES. Every
CometChatCallDelegate member is @objc optional, so a near-miss label is simply a
new, unrelated method — and the app's cancel handler silently never fires. A
review emit built from this page shipped exactly that dead handler and passed
every gate: compile (G5) accepts it, and the live round-trip (G6) never
exercises the cancel path. The Swift compiler's "nearly matches optional
requirement" warning was the only signal.

Verified against the shipped .swiftinterface (Swift) and CometChatSDK-Swift.h
(Objective-C). Other platforms' ringing pages are untouched — their SDKs spell
their own labels.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…alse System PiP claim

Both found by a black-box explorer pass building a from-scratch iOS app against
the corrected preview. Both survive `swiftc` and fail silently at runtime, which
is why review gates never caught them.

D14 — `MediaEventsListener.onScreenShareStarted` / `onScreenShareStopped` do not
exist. Zero occurrences in the shipped CometChatCallsSDK 5.0.4 .swiftinterface
AND zero in the framework binary; the protocol's 11 real members carry no
screen-share callback. Because every member is `@objc optional`, writing them
compiles cleanly and then never fires — the same silent-death class as D13's
`canceledCall` label. Removed from `events` (code sample + two reference-table
rows) and from the copy-paste stubs in `audio-modes`, `custom-control-panel` and
`recording` — 6 occurrences over 4 pages. `events` now states where screen share
IS observed: `ParticipantEventListener.onParticipantStartedScreenShare` /
`onParticipantStoppedScreenShare`, and that on iOS those are receive-only (no
local capture without a Broadcast Upload Extension).

CORRECTING MYSELF — the PiP rewrite earlier in this PR asserted "The Calls SDK
does **not** implement System PiP. If you need the call to float over other apps,
that part is Apple's API and yours to wire." That is FALSE. The 5.0.4 framework
links AVKit in its load commands and carries the whole path —
AVPictureInPictureController (16 refs), AVPictureInPictureControllerContentSource,
AVPictureInPictureVideoCallViewController — gated behind an undocumented
`SessionSettingsBuilder.enableIOSPictureInPicture(_:)`, a real setter in the
interface. I inferred absence from PiPViewCoordinator being the in-app mechanism
and never checked the binary. Undocumented is not the same as absent, and a
NEGATIVE capability claim needs the same evidence as a positive one. The page now
documents the flag plus the Background Modes capability, and keeps hosting
AVPictureInPictureController yourself as the full-control option.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>